IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat2/standard/getmsg.z/getmsg

Text File | 2002-10-03 | 14.8 KB | 199 lines

ggggeeeettttmmmmssssgggg((((2222))))                                                            ggggeeeettttmmmmssssgggg((((2222))))



NNNNAAAAMMMMEEEE
     _gggg_eeee_tttt_mmmm_ssss_gggg - get next message off a stream

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_rrrr_oooo_pppp_tttt_ssss_...._hhhh_>>>>

     _iiii_nnnn_tttt _gggg_eeee_tttt_mmmm_ssss_gggg_((((_iiii_nnnn_tttt _ffff_dddd_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_cccc_tttt_llll_pppp_tttt_rrrr_,,,,
                    _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_dddd_aaaa_tttt_aaaa_pppp_tttt_rrrr_,,,, _iiii_nnnn_tttt _****_ffff_llll_aaaa_gggg_ssss_pppp_))))_;;;;

     _iiii_nnnn_tttt _gggg_eeee_tttt_pppp_mmmm_ssss_gggg_((((_iiii_nnnn_tttt _ffff_dddd_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_cccc_tttt_llll_pppp_tttt_rrrr_,,,,
                     _ssss_tttt_rrrr_uuuu_cccc_tttt _ssss_tttt_rrrr_bbbb_uuuu_ffff _****_dddd_aaaa_tttt_aaaa_pppp_tttt_rrrr_,,,, _iiii_nnnn_tttt _****_bbbb_aaaa_nnnn_dddd_pppp_,,,, _iiii_nnnn_tttt _****_ffff_llll_aaaa_gggg_ssss_pppp_))))_;;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _gggg_eeee_tttt_mmmm_ssss_gggg retrieves the contents of a message [see _iiii_nnnn_tttt_rrrr_oooo(2)] located at the
     stream head read queue from a STREAMS file, and places the contents into
     user specified buffer(s).  The message must contain either a data part, a
     control part, or both.  The data and control parts of the message are
     placed into separate buffers, as described below.  The semantics of each
     part is defined by the STREAMS module that generated the message.

     The function _gggg_eeee_tttt_pppp_mmmm_ssss_gggg does the same thing as _gggg_eeee_tttt_mmmm_ssss_gggg, but provides finer
     control over the priority of the messages received.  Except where noted,
     all information pertaining to _gggg_eeee_tttt_mmmm_ssss_gggg also pertains to _gggg_eeee_tttt_pppp_mmmm_ssss_gggg.

     _f_d specifies a file descriptor referencing an open stream.  _c_t_l_p_t_r and
     _d_a_t_a_p_t_r each point to a _ssss_tttt_rrrr_bbbb_uuuu_ffff structure, which contains the following
     members:

          _iiii_nnnn_tttt _mmmm_aaaa_xxxx_llll_eeee_nnnn_;;;;     _////_**** _mmmm_aaaa_xxxx_iiii_mmmm_uuuu_mmmm _bbbb_uuuu_ffff_ffff_eeee_rrrr _llll_eeee_nnnn_gggg_tttt_hhhh _****_////
          _iiii_nnnn_tttt _llll_eeee_nnnn_;;;;        _////_**** _llll_eeee_nnnn_gggg_tttt_hhhh _oooo_ffff _dddd_aaaa_tttt_aaaa _****_////
          _cccc_hhhh_aaaa_rrrr _****_bbbb_uuuu_ffff_;;;;      _////_**** _pppp_tttt_rrrr _tttt_oooo _bbbb_uuuu_ffff_ffff_eeee_rrrr _****_////

     _bbbb_uuuu_ffff points to a buffer in which the data or control information is to be
     placed, and _mmmm_aaaa_xxxx_llll_eeee_nnnn indicates the maximum number of bytes this buffer can
     hold.  On return, _llll_eeee_nnnn contains the number of bytes of data or control
     information actually received, or 0 if there is a zero-length control or
     data part, or -1 if no data or control information is present in the
     message.  _f_l_a_g_s_p should point to an integer that indicates the type of
     message the user is able to receive.  This is described later.

     _c_t_l_p_t_r is used to hold the control part from the message and _d_a_t_a_p_t_r is
     used to hold the data part from the message.  If _c_t_l_p_t_r (or _d_a_t_a_p_t_r) is
     _NNNN_UUUU_LLLL_LLLL or the _mmmm_aaaa_xxxx_llll_eeee_nnnn field is -1, the control (or data) part of the message
     is not processed and is left on the stream head read queue.  If _c_t_l_p_t_r
     (or _d_a_t_a_p_t_r) is not _NNNN_UUUU_LLLL_LLLL and there is no corresponding control (or data)
     part of the messages on the stream head read queue, _llll_eeee_nnnn is set to -1.  If
     the _mmmm_aaaa_xxxx_llll_eeee_nnnn field is set to 0 and there is a zero-length control (or data)
     part, that zero-length part is removed from the read queue and _llll_eeee_nnnn is set
     to 0.  If the _mmmm_aaaa_xxxx_llll_eeee_nnnn field is set to 0 and there are more than zero bytes
     of control (or data) information, that information is left on the read
     queue and _llll_eeee_nnnn is set to 0.  If the _mmmm_aaaa_xxxx_llll_eeee_nnnn field in _c_t_l_p_t_r or _d_a_t_a_p_t_r is
     less than, respectively, the control or data part of the message, _mmmm_aaaa_xxxx_llll_eeee_nnnn



                                                                        PPPPaaaaggggeeee 1111






ggggeeeettttmmmmssssgggg((((2222))))                                                            ggggeeeettttmmmmssssgggg((((2222))))



     bytes are retrieved.  In this case, the remainder of the message is left
     on the stream head read queue and a non-zero return value is provided, as
     described below under DIAGNOSTICS.

     By default, _gggg_eeee_tttt_mmmm_ssss_gggg processes the first available message on the stream
     head read queue.  However, a user may choose to retrieve only high
     priority messages by setting the integer pointed by _f_l_a_g_s_p to _RRRR_SSSS______HHHH_IIII_PPPP_RRRR_IIII.
     In this case, _gggg_eeee_tttt_mmmm_ssss_gggg processes the next message only if it is a high
     priority message.  If the integer pointed by _f_l_a_g_s_p is 0, _gggg_eeee_tttt_mmmm_ssss_gggg
     retrieves any message available on the stream head read queue.  In this
     case, on return, the integer pointed to by _f_l_a_g_s_p will be set to _RRRR_SSSS______HHHH_IIII_PPPP_RRRR_IIII
     if a high priority message was retrieved, or 0 otherwise.

     For _gggg_eeee_tttt_pppp_mmmm_ssss_gggg, the flags are different.  _f_l_a_g_s_p points to a bitmask with
     the following mutually-exclusive flags defined:  _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII_,,,, _MMMM_SSSS_GGGG______BBBB_AAAA_NNNN_DDDD, and
     _MMMM_SSSS_GGGG______AAAA_NNNN_YYYY.  Like _gggg_eeee_tttt_mmmm_ssss_gggg, _gggg_eeee_tttt_pppp_mmmm_ssss_gggg processes the first available message on
     the stream head read queue.  A user may choose to retrieve only high-
     priority messages by setting the integer pointed to by _f_l_a_g_s_p to
     _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII and the integer pointed to by _b_a_n_d_p to 0.  In this case,
     _gggg_eeee_tttt_pppp_mmmm_ssss_gggg will only process the next message if it is a high-priority
     message.  In a similar manner, a user may choose to retrieve a message
     from a particular priority band by setting the integer pointed to by
     _f_l_a_g_s_p to _MMMM_SSSS_GGGG______BBBB_AAAA_NNNN_DDDD and the integer pointed to by _b_a_n_d_p to the priority
     band of interest.  In this case, _gggg_eeee_tttt_pppp_mmmm_ssss_gggg will only process the next
     message if it is in a priority band equal to, or greater than, the
     integer pointed to by _b_a_n_d_p, or if it is a high-priority message.  If a
     user just wants to get the first message off the queue, the integer
     pointed to by _f_l_a_g_s_p should be set to _MMMM_SSSS_GGGG______AAAA_NNNN_YYYY and the integer pointed to
     by _b_a_n_d_p should be set to 0.  On return, if the message retrieved was a
     high-priority message, the integer pointed to by _f_l_a_g_s_p will be set to
     _MMMM_SSSS_GGGG______HHHH_IIII_PPPP_RRRR_IIII and the integer pointed to by _b_a_n_d_p will be set to 0.
     Otherwise, the integer pointed to by _f_l_a_g_s_p will be set to _MMMM_SSSS_GGGG______BBBB_AAAA_NNNN_DDDD and
     the integer pointed to by _b_a_n_d_p will be set to the priority band of the
     message.

     If _OOOO______NNNN_DDDD_EEEE_LLLL_AAAA_YYYY and _OOOO______NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK are clear, _gggg_eeee_tttt_mmmm_ssss_gggg blocks until a message of
     the type specified by _f_l_a_g_s_p is available on the stream head read queue.
     If _OOOO______NNNN_DDDD_EEEE_LLLL_AAAA_YYYY or _OOOO______NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK has been set and a message of the specified
     type is not present on the read queue, _gggg_eeee_tttt_mmmm_ssss_gggg fails and sets _eeee_rrrr_rrrr_nnnn_oooo to
     _EEEE_AAAA_GGGG_AAAA_IIII_NNNN.

     If a hangup occurs on the stream from which messages are to be retrieved,
     _gggg_eeee_tttt_mmmm_ssss_gggg continues to operate normally, as described above, until the
     stream head read queue is empty.  Thereafter, it returns 0 in the _llll_eeee_nnnn
     fields of _c_t_l_p_t_r and _d_a_t_a_p_t_r.

     _gggg_eeee_tttt_mmmm_ssss_gggg or _gggg_eeee_tttt_pppp_mmmm_ssss_gggg will fail if one or more of the following are true:

     _EEEE_AAAA_GGGG_AAAA_IIII_NNNN         The _OOOO______NNNN_DDDD_EEEE_LLLL_AAAA_YYYY or _OOOO______NNNN_OOOO_NNNN_BBBB_LLLL_OOOO_CCCC_KKKK flag is set, and no messages
                    are available.





                                                                        PPPPaaaaggggeeee 2222






ggggeeeettttmmmmssssgggg((((2222))))                                                            ggggeeeettttmmmmssssgggg((((2222))))



     _EEEE_BBBB_AAAA_DDDD_FFFF          _f_d is not a valid file descriptor open for reading.

     _EEEE_BBBB_AAAA_DDDD_MMMM_SSSS_GGGG        Queued message to be read is not valid for _gggg_eeee_tttt_mmmm_ssss_gggg.

     _EEEE_FFFF_AAAA_UUUU_LLLL_TTTT         _c_t_l_p_t_r, _d_a_t_a_p_t_r, _b_a_n_d_p, or _f_l_a_g_s_p points to a location
                    outside the allocated address space.

     _EEEE_IIII_NNNN_TTTT_RRRR          A signal was caught during the _gggg_eeee_tttt_mmmm_ssss_gggg system call.

     _EEEE_IIII_NNNN_VVVV_AAAA_LLLL         An illegal value was specified in _f_l_a_g_s_p, or the stream
                    referenced by _f_d is linked under a multiplexor.

     _EEEE_NNNN_OOOO_SSSS_TTTT_RRRR         A stream is not associated with _f_d.

     _EEEE_IIII_OOOO            _f_i_l_d_e_s points to an open device that is in the process of
                    closing.

     _EEEE_AAAA_CCCC_CCCC_EEEE_SSSS         _f_i_l_d_e_s points to a dynamic device and read permission on
                    the device is denied.

     _gggg_eeee_tttt_mmmm_ssss_gggg can also fail if a STREAMS error message had been received at the
     stream head before the call to _gggg_eeee_tttt_mmmm_ssss_gggg.  The error returned is the value
     contained in the STREAMS error message.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     _iiii_nnnn_tttt_rrrr_oooo(2), _pppp_oooo_llll_llll(2), _pppp_uuuu_tttt_mmmm_ssss_gggg(2), _rrrr_eeee_aaaa_dddd(2), _wwww_rrrr_iiii_tttt_eeee(2)

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     Upon successful completion, a non-negative value is returned.  A value of
     0 indicates that a full message was read successfully.  A return value of
     _MMMM_OOOO_RRRR_EEEE_CCCC_TTTT_LLLL indicates that more control information is waiting for retrieval.
     A return value of _MMMM_OOOO_RRRR_EEEE_DDDD_AAAA_TTTT_AAAA indicates that more data is waiting for
     retrieval.  A return value of _MMMM_OOOO_RRRR_EEEE_CCCC_TTTT_LLLL _|||| _MMMM_OOOO_RRRR_EEEE_DDDD_AAAA_TTTT_AAAA indicates that both
     types of information remain.  Subsequent _gggg_eeee_tttt_mmmm_ssss_gggg calls retrieve the
     remainder of the message.  However, if a message of higher priority has
     come in on the stream head read queue, the next call to _gggg_eeee_tttt_mmmm_ssss_gggg will
     retrieve that higher priority message before retrieving the remainder of
     the previously received partial message.

















                                                                        PPPPaaaaggggeeee 3333